<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Loop</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Loop (normal)</h1>

<p>Perform a series of commands repeatedly: either the specified number of times or until <a href="Break.htm">break</a> is encountered.</p>

<pre class="Syntax">Loop [, Count]</pre>
<h3>Parameters</h3>
<dl>

  <dt>Count</dt>
  <dd><p>How many times (iterations) to perform the loop. If omitted, the Loop continues indefinitely until a <a href="Break.htm">break</a> or <a href="Return.htm">return</a> is encountered.</p>
      <p>If <em>Count</em> is a variable reference such as %ItemCount%, the loop is skipped entirely whenever the variable is blank or contains a number less than 1.</p>
      <p>Due to the need to support <a href="LoopFile.htm">file-pattern loops</a>, <em>Count</em> cannot be an expression. However, as with all non-expression parameters, an expression can be forcibly used by preceding it with a % and a space. For example: <code>Loop % Count + 1</code>. In such cases, the expression is evaluated only once, right before the loop begins.</p></dd>

</dl>

<h3>Remarks</h3>
<p>The loop command is usually followed by a <a href="Block.htm">block</a>, which is a collection of statements that form the <em>body</em> of the loop. However, a loop with only a single statement does not require a block (an &quot;if&quot; and its &quot;else&quot; count as a single statement for this purpose).</p>
<p>A common use of this command is an infinite loop that uses the <a href="Break.htm">break</a> command somewhere in the loop's <em>body</em> to determine when to stop the loop.</p>
<p>The use of <a href="Break.htm">break</a> and <a href="Continue.htm">continue</a> inside a loop are encouraged as alternatives to <a href="Goto.htm">goto</a>, since they generally make a script more understandable and maintainable. To create a &quot;Do...While&quot; loop, make the last statement of the loop's <em>body</em> an IF statement that conditionally issues the <a href="Break.htm">break</a> command. The same technique can be used to create a &quot;While&quot; loop, but the <a href="While.htm">While</a> command should be used instead.</p>
<p>The built-in variable <strong>A_Index</strong> contains the number of the current loop iteration. It contains 1 the first time the loop's <em>body</em> is executed. For the second time, it contains 2; and so on. If an inner loop is enclosed by an outer loop, the inner loop takes precedence. A_Index works inside all types of loops, including <a href="LoopFile.htm">file-loops</a> and <a href="LoopReg.htm">registry-loops</a>; but A_Index contains 0 outside of a loop.</p>
<p>The <a href="Block.htm#otb">One True Brace (OTB) style</a> may optionally be used with normal loops (but not specialized loops such as <a href="LoopFile.htm">file-pattern</a> and <a href="LoopParse.htm">parsing</a>). For example:</p>
<pre>Loop <strong>{</strong>
    ...
<strong>}</strong>
Loop %RepeatCount% <strong>{</strong>
    ...
<strong>}</strong></pre>
<p>Specialized loops: Loops can be used to automatically retrieve files, folders, or registry items (one at a time). See <a href="LoopFile.htm">file-loop</a> and <a href="LoopReg.htm">registry-loop</a> for details. In addition, <a href="LoopReadFile.htm">file-reading loops</a> can operate on the entire contents of a file, one line at a time. Finally, <a href="LoopParse.htm">parsing loops</a> can operate on the individual fields contained inside a delimited string.</p>
<h3>Related</h3>
<p><a href="Until.htm">Until</a>, <a href="While.htm">While-loop</a>, <a href="For.htm">For-loop</a>, <a href="LoopFile.htm">Files-and-folders loop</a>, <a href="LoopReg.htm">Registry loop</a>, <a href="LoopReadFile.htm">File-reading loop</a>, <a href="LoopParse.htm">Parsing loop</a>, <a href="Break.htm">Break</a>, <a href="Continue.htm">Continue</a>, <a href="Block.htm">Blocks</a></p>
<h3>Examples</h3>
<pre class="NoIndent">Loop, 3
{
    MsgBox, Iteration number is %A_Index%.  <em>; A_Index will be 1, 2, then 3</em>
    Sleep, 100
}

Loop
{
    if a_index &gt; 25
        break  <em>; Terminate the loop</em>
    if a_index &lt; 20
        continue <em>; Skip the below and start a new iteration</em>
    MsgBox, a_index = %a_index% <em>; This will display only the numbers 20 through 25</em>
}</pre>

</body>
</html>
